<?php

interface GDGE_Storage_Interface
{
	
	/**
	 * Put resource(s) into this storage.
	 * 
	 * $resource may be a resource identifier, and $value the what to put in
	 * or, $resource may be an array, with resource identifier as keys and what to put
	 * in as value
	 * 
	 * @param mixed $resource
	 * @param mixed $value
	 * @throws GDGE_Storage_Exception on invalid resource, or if storage is full
	 */
	public function put($resource, $value = null);
	
	/**
	 * Same as put, only here you take resources out.
	 * 
	 * returns an array of resources taken if successful.
	 * 
	 * @param mixed $resource
	 * @param mixed $value
	 * @return array resources taken
	 * @throws GDGE_Storage_Exception on invalid resource, or if there is not enough resources
	 */
	public function take($resource, $value = null);
	
	/**
	 * Set the resource(s) to a spesific value.
	 * 
	 * Supports array same as take and put
	 * 
	 * @param mixed $resource
	 * @param mixed $value
	 */
	public function set($resource, $value = null);
	
	/**
	 * Returns an array of the resources in this storage
	 * @return array
	 */
	public function viewAll();
	
	/**
	 * Returns a spesific resource, or null if this resource is not
	 * in storage at the moment.
	 * @param mixed $resource
	 * @throws GDGE_Storage_Exception on invalid resource
	 */
	public function view($resource);
	
	/**
	 * Returns true if $resource is a valid resource for this storage
	 * @param mixed $resource
	 * @return boolean true if valid resource
	 */
	public function isValid($resource);
}